

    \filetitle{dbload}{Create database by loading CSV file}{dbase/dbload}

	\paragraph{Syntax}

\begin{verbatim}
D = dbload(FName, ...)
D = dbload(D,FName, ...)
\end{verbatim}

\paragraph{Input arguments}

\begin{itemize}
\item
  \texttt{FName} {[} char \textbar{} cellstr {]} - Name of the Input CSV
  data file or a cell array of CSV file names that will be combined.
\item
  \texttt{D} {[} struct {]} - An existing database (struct) to which the
  new entries from the input CSV data file entries will be added.
\end{itemize}

\paragraph{Output arguments}

\begin{itemize}
\tightlist
\item
  \texttt{D} {[} struct {]} - Database created from the input CSV
  file(s).
\end{itemize}

\paragraph{Options}

\begin{itemize}
\item
  \texttt{\textquotesingle{}case=\textquotesingle{}} {[}
  \texttt{\textquotesingle{}lower\textquotesingle{}} \textbar{}
  \texttt{\textquotesingle{}upper\textquotesingle{}} \textbar{}
  \emph{empty} {]} - Change case of variable names.
\item
  \texttt{\textquotesingle{}commentRow=\textquotesingle{}} {[} char
  \textbar{} cellstr \textbar{}
  \emph{\texttt{\{\textquotesingle{}comment\textquotesingle{},\textquotesingle{}comments\textquotesingle{}\}}}
  {]} - Label at the start of row that will be used to create tseries
  object comments.
\item
  \texttt{\textquotesingle{}dateFormat=\textquotesingle{}} {[} char
  \textbar{} \emph{\texttt{\textquotesingle{}YYYYFP\textquotesingle{}}}
  {]} - Format of dates in first column.
\item
  \texttt{\textquotesingle{}delimiter=\textquotesingle{}} {[} char
  \textbar{} \emph{\texttt{\textquotesingle{},\textquotesingle{}}} {]} -
  Delimiter separating the individual values (cells) in the CSV file; if
  different from a comma, all occurences of the delimiter will replaced
  with commas -- note that this will also affect text in comments.
\item
  \texttt{\textquotesingle{}firstDateOnly=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - Read and parse
  only the first date string, and fill in the remaining dates assuming a
  range of consecutive dates.
\item
  \texttt{\textquotesingle{}freq=\textquotesingle{}} {[} \texttt{0}
  \textbar{} \texttt{1} \textbar{} \texttt{2} \textbar{} \texttt{4}
  \textbar{} \texttt{6} \textbar{} \texttt{12} \textbar{} \texttt{365}
  \textbar{} \texttt{\textquotesingle{}daily\textquotesingle{}}
  \textbar{} \emph{empty} {]} - Advise frequency of dates; if empty,
  frequency will be automatically recognised.
\item
  \texttt{\textquotesingle{}freqLetters=\textquotesingle{}} {[} char
  \textbar{} \emph{\texttt{\textquotesingle{}YHQBM\textquotesingle{}}}
  {]} - Letters representing frequency of dates in date column.
\item
  \texttt{\textquotesingle{}inputFormat=\textquotesingle{}} {[}
  \emph{\texttt{\textquotesingle{}auto\textquotesingle{}}} \textbar{}
  \texttt{\textquotesingle{}csv\textquotesingle{}} \textbar{}
  \texttt{\textquotesingle{}xls\textquotesingle{}} {]} - Format of input
  data file; \texttt{\textquotesingle{}auto\textquotesingle{}} means the
  format will be determined by the file extension.
\item
  \texttt{\textquotesingle{}nameRow=\textquotesingle{}} {[} char
  \textbar{} numeric \textbar{}
  \emph{\texttt{\{\textquotesingle{}\textquotesingle{},\textquotesingle{}Variables\textquotesingle{}\}}}
  {]} - String, or cell array of possible strings, that is found at the
  beginning (in the first cell) of the row with variable names, or the
  line number at which the row with variable names appears (first row is
  numbered 1).
\item
  \texttt{\textquotesingle{}nameFunc=\textquotesingle{}} {[} cell
  \textbar{} function\_handle \textbar{} \emph{empty} {]} - Function
  used to change or transform the variable names. If a cell array of
  function handles, each function will be applied in the given order.
\item
  \texttt{\textquotesingle{}nan=\textquotesingle{}} {[} char \textbar{}
  \emph{\texttt{NaN}} {]} - String representing missing observations
  (case insensitive).
\item
  \texttt{\textquotesingle{}preProcess=\textquotesingle{}} {[}
  function\_handle \textbar{} cell \textbar{} \emph{empty} {]} - Apply
  this function, or cell array of functions, to the raw text file before
  parsing the data.
\item
  \texttt{\textquotesingle{}select=\textquotesingle{}} {[} char
  \textbar{} cellstr \textbar{} \emph{empty} {]} - Only database entries
  included on this list will be read in and returned in the output
  database \texttt{D}; entries not on this list will be discarded.
\item
  \texttt{\textquotesingle{}skipRows=\textquotesingle{}} {[} char
  \textbar{} cellstr \textbar{} numeric \textbar{} \emph{empty} {]} -
  Skip rows whose first cell matches the string or strings (regular
  expressions); or, skip a vector of row numbers.
\item
  \texttt{\textquotesingle{}userData=\textquotesingle{}} {[} char
  \textbar{} \emph{\texttt{Inf}} {]} - Field name under which the
  database userdata loaded from the CSV file (if they exist) will be
  stored in the output database; \texttt{Inf} means the field name will
  be read from the CSV file (and will be thus identical to the
  originally saved database).
\item
  \texttt{\textquotesingle{}userDataField=\textquotesingle{}} {[} char
  \textbar{} \emph{\texttt{\textquotesingle{}.\textquotesingle{}}} {]} -
  A leading character denoting userdata fields for individual time
  series; if empty, no userdata fields will be read in and created.
\item
  \texttt{\textquotesingle{}userDataFieldList=\textquotesingle{}} {[}
  cellstr \textbar{} numeric \textbar{} empty {]} - List of row headers,
  or vector of row numbers, that will be included as user data in each
  time series.
\end{itemize}

\paragraph{Description}

Use the \texttt{\textquotesingle{}freq=\textquotesingle{}} option
whenever there is ambiguity in intepreting the date strings, and IRIS is
not able to determine the frequency correctly (see Example).

\subparagraph{Structure of CSV database
files}

The minimalist structure of a CSV database file has a leading row with
variables names, a leading column with dates in the basic IRIS format,
and individual columns with numeric data:

\begin{verbatim}
+---------+---------+---------+--
|         |       Y |       P |
+---------+---------+---------+--
|  2010Q1 |       1 |      10 |
+---------+---------+---------+--
|  2010Q2 |       2 |      20 |
+---------+---------+---------+--
|         |         |         |
\end{verbatim}

You can add a comment row (must be placed before the data part, and
start with a label `Comment' in the first cell) that will also be read
in and assigned as comments to the individual tseries objects created in
the output database.

\begin{verbatim}
+---------+---------+---------+--
|         |       Y |       P |
+---------+---------+---------+--
| Comment |  Output |  Prices |
+---------+---------+---------+--
|  2010Q1 |       1 |      10 |
+---------+---------+---------+--
|  2010Q2 |       2 |      20 |
+---------+---------+---------+--
|         |         |         |
\end{verbatim}

You can use a different label in the first cell to denote a comment row;
in that case you need to set the option
\texttt{\textquotesingle{}commentRow=\textquotesingle{}} accordingly.

All CSV rows whose names start with a character specified in the option
\texttt{\textquotesingle{}userdataField=\textquotesingle{}} (a dot by
default) will be added to output tseries objects as fields of their
userdata.

\begin{verbatim}
+---------+---------+---------+--
|         |       Y |       P |
+---------+---------+---------+--
| Comment |  Output |  Prices |
+---------+---------+---------+--
| .Source |   Stat  |  IMFIFS |
+---------+---------+---------+--
| .Update | 17Feb11 | 01Feb11 |
+---------+---------+---------+--
| .Units  | Bil USD |  2010=1 |
+---------+---------+---------+--
|  2010Q1 |       1 |      10 |
+---------+---------+---------+--
|  2010Q2 |       2 |      20 |
+---------+---------+---------+--
|         |         |         |
\end{verbatim}

\paragraph{Example}

Typical example of using the
\texttt{\textquotesingle{}freq=\textquotesingle{}} option is a quarterly
database with dates represented by the corresponding months, such as a
sequence 2000-01-01, 2000-04-01, 2000-07-01, 2000-10-01, etc. In this
case, you can use the following options:

\begin{verbatim}
d = dbload('filename.csv','dateFormat','YYYY-MM-01','freq',4);
\end{verbatim}


